<!DOCTYPE html>
<html lang="en-US">
    <head>
        <title>Log::Message - A generic message storing mechanism; - metacpan.org</title>
        <link rel="preload" as="fetch" href="https://metacpan.org/account/login_status" crossorigin="anonymous" />
        <link href="https://metacpan.org/_assets/b8ccceeed47a0652049703d99326a9cea4933443.css" rel="stylesheet" type="text/css">
        <script src="https://metacpan.org/_assets/6bfedafe2d7caa915b7d84f61b45936818e3242e.js" type="text/javascript" defer></script>
        <link rel="alternate" type="application/rss+xml" title="Recent CPAN Uploads of Log-Message - MetaCPAN" href="https://metacpan.org/dist/Log-Message/releases.rss" />
        <link rel="canonical" href="./Log::Message.html" />
        <meta name="description" content="A generic message storing mechanism;" />
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">
        <link rel="shortcut icon" href="https://metacpan.org/static/icons/favicon.ico">
        <link rel="apple-touch-icon" sizes="152x152" href="https://metacpan.org/static/icons/apple-touch-icon.png">
        <link rel="search" href="https://metacpan.org/static/opensearch.xml" type="application/opensearchdescription+xml" title="MetaCPAN">
        <script>
          (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
          })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

          (function(skey, ga_id){
            ga('create', ga_id, {
              siteSpeedSampleRate : 100,
              storage             : 'none',
              clientId            : localStorage.getItem(skey)
            });
            ga(function(tracker) {
              localStorage.setItem(skey, tracker.get('clientId'));
            });
            ga('send', 'pageview');
          })('ga:clientId', 'UA-27829474-1');
        </script>
<meta name="twitter:card"        content="summary" />
<meta name="twitter:url"         content="https://metacpan.org/pod/Log::Message" />
<meta name="twitter:title"       content="Log::Message" />
<meta name="twitter:description" content="A generic message storing mechanism;" />
<meta name="twitter:site"        content="metacpan" />
    </head>
    <body>
        <nav class="navbar navbar-default" role="navigation">
            <div class="header-logo-large hidden-xs">
              <a href="https://metacpan.org/" tabindex="0">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#logo" />
                </svg>
              </a>
            </div>
            <div class="header-logo-icon visible-xs">
              <a href="https://metacpan.org/">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#dots" />
                </svg>
              </a>
            </div>
            <ul class="nav navbar-nav menu-items hidden-xs hidden-sm">
              <li><a href="https://metacpan.org/about">About</a></li>
              <li><a href="https://metacpan.org/about/sponsors">Sponsor</a></li>
              <li><a href="https://grep.metacpan.org/">grep::cpan</a></li>
              <li><a href="https://metacpan.org/recent">Recent</a></li>
              <li><a href="https://metacpan.org/about/faq">FAQ</a></li>
              <li><a href="https://metacpan.org/tools">Tools</a></li>
              <li><a href="https://fastapi.metacpan.org/">API</a></li>
            </ul>
            <ul class="nav navbar-nav navbar-right">
                <button type="button" class="searchbar-btn visible-xs visible-sm">
                    <i class="fa fa-search button-fa-icon"></i>
                </button>
                <form action="https://metacpan.org/search" class="searchbar-form visible-md visible-lg search-form form-horizontal">
                   <input type="hidden" name="size" id="metacpan_search-size" value="20">
                  <div class="form-group">
                      <div class="search-group">
                        <i class="fa fa-search"></i>
                        <input type="text" name="q" placeholder="Search the CPAN" size="41" autocorrect="off" autocapitalize="off" spellcheck="false" id="metacpan_search-input" class="form-control" value="">
                      </div>
                  </div>
                </form>
                    <li class="icon-slidepanel visible-xs visible-sm">
                      <button data-toggle="slidepanel" data-target=".slidepanel">
                        <span class="button-fa-icon">
                          <i class="fa fa-bars slidepanel-open"></i>
                          <i class="fa fa-times slidepanel-close"></i>
                        </span>
                      </button>
                    </li>
                <form action="https://metacpan.org/account/logout" method="POST" id="metacpan-logout"></form>
                <li class="dropdown logged_in" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon logged-in-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li><a href="https://metacpan.org/account/identities">Identities</a></li>
                        <li><a href="https://metacpan.org/account/profile">Profile</a></li>
                        <li><a href="https://metacpan.org/account/favorite/list">Favorites</a></li>
                        <li>
                            <a href="./Log::Message.html#" type="button" onclick="$('#metacpan-logout').submit(); return false">
                              Logout
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_out" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li>
                            <a href="https://metacpan.org/login/github">
                                <i class="fab fa-github fa-fw"></i>
                                GitHub
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/twitter">
                                <i class="fab fa-twitter fa-fw"></i>
                                Twitter
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/google">
                                <i class="fab fa-google fa-fw"></i>
                                Google
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_placeholder">
                    <button>
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                    </button>
                </li>
            </ul>
        </nav>
        <div class="page-content ">
          <!--
          <div class="top-notify-banner">
            <i class="fas fa-info-circle"></i>
          </div>
          -->
          <nav class="sidebar">
            <div class="slidepanel">
              <ul class="nav-list ">
    <li class="nav-header no-margin-top">
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The date that this version of Log-Message was released.">
      <span class="relatize">25 Apr 2013 22:23:39 UTC</span>
    </li>
  <li>
    Distribution: <a href="https://metacpan.org/dist/Log-Message">Log-Message</a>
  </li>
  <li>
    Module version: 0.08
  </li>
  <li>
    <a data-keyboard-shortcut="g s" href="https://metacpan.org/dist/Log-Message/source/lib/Log/Message.pm">Source</a>
    (<a href="https://metacpan.org/dist/Log-Message/source/lib/Log/Message.pm?raw=1">raw</a>)
  </li>
  <li>
    <a data-keyboard-shortcut="g b" href="https://metacpan.org/dist/Log-Message/source/lib/Log">Browse</a>
    (<a href="https://metacpan.org/dist/Log-Message/source/lib/Log?raw=1">raw</a>)
  </li>
    <li>
      <a data-keyboard-shortcut="g c" href="https://metacpan.org/dist/Log-Message/changes">Changes</a>
    </li>
    <li>
      <a class="nopopup" href="https://metacpan.org/dist/Log-Message/contribute">How to Contribute</a>
    </li>
    <li>
        <a rel="noopener nofollow" data-keyboard-shortcut="g r" href="https://github.com/jib/log-message">Repository</a>
    </li>
    <li>
      <a rel="noopener nofollow" data-keyboard-shortcut="g i" href="https://rt.cpan.org/Public/Dist/Display.html?Name=Log-Message">Issues</a>
      (0)
    </li>
    <li>
      <a rel="noopener nofollow" href="http://matrix.cpantesters.org/?dist=Log-Message+0.08" title="Matrix">Testers</a>
        <span title="(pass / fail / na)">(<a rel="noopener nofollow" href="https://www.cpantesters.org/distro/L/Log-Message.html?oncpan=1&amp;distmat=1&amp;version=0.08&amp;grade=2" style="color: #090">265</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/L/Log-Message.html?oncpan=1&amp;distmat=1&amp;version=0.08&amp;grade=3" style="color: #900">0</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/L/Log-Message.html?oncpan=1&amp;distmat=1&amp;version=0.08&amp;grade=4">0</a>)</span>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpants.cpanauthors.org/release/BINGOS/Log-Message-0.08">Kwalitee</a>
    </li>
    <li>
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The # people with an indexing permission on Log-Message who have released something to CPAN in the last 2 years (i.e. the # people likely able to release critical fixes in a timely manner)">
      Bus factor: 1
      </div>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpancover.com/latest/Log-Message-0.08/index.html">87.84% Coverage </a>
    </li>
    <li>
      License: perl_5
    </li>
    <li class="nav-header">Activity</li>
    <li>
<div class="activity-graph">
    <img src="https://metacpan.org/dist/Log-Message/activity.svg?res=month" />
    <div class="comment">24 month</div>
</div>
    </li>
    <li class="nav-header">Tools</li>
    <li>
      <a itemprop="downloadUrl" href="https://cpan.metacpan.org/authors/id/B/BI/BINGOS/Log-Message-0.08.tar.gz">
      Download (<span itemprop="fileSize">12.21KB</span>)</a>
    </li>
    <li>
      <a href="https://explorer.metacpan.org/?url=%2Fmodule%2FBINGOS%2FLog-Message-0.08%2Flib%2FLog%2FMessage.pm">
        MetaCPAN Explorer
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Log-Message/permissions">
        Permissions
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Log-Message/releases.rss">
        Subscribe to distribution
      </a>
    </li>
    <li>
      <button class="btn btn-link" data-toggle="modal" data-target="#metacpan_install-instructions-dialog">
        Install Instructions
      </button>
    </li>
    <li>
      <form action="https://metacpan.org/search">
        <input type="hidden" name="q" value="dist:Log-Message">
        <input type="search" name="q" placeholder="Search distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
      </form>
    </li>
    <li>
      <form action="https://grep.metacpan.org/search">
        <input type="hidden" name="qd" value="Log-Message">
        <input type="hidden" name="source" value="metacpan">
        <input type="search" name="q" placeholder="grep distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
     </form>
    </li>
    <li class="version-jump">
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/lib/Log/Message.pm&#39;" class="form-control tool-bar-form">
  <option disabled selected>Jump to version</option>
<option
  disabled
  value="BINGOS/Log-Message-0.08"
>0.08
  (BINGOS on 2013-04-25)</option>
<option
  
  value="KANE/Log-Message-0.02"
>0.02
  (KANE on 2008-12-13)</option>
<option
  
  value="KANE/Log-Message-0.01"
>0.01
  (KANE on 2003-05-10)</option>
<optgroup label="BackPAN">'
<option
  
  value="BINGOS/Log-Message-0.06"
>0.06
  (BINGOS on 2013-01-23)</option>
<option
  
  value="BINGOS/Log-Message-0.04"
>0.04
  (BINGOS on 2011-01-07)</option>
</optgroup>
</select>
    </li>
    <li class="version-diff">
<select onchange="document.location.href='/release/BINGOS/Log-Message-0.08/diff/' + encodeURIComponent(this.value) + '/lib/Log/Message.pm'
" class="form-control tool-bar-form">
  <option disabled selected>Diff with version</option>
<option
  disabled
  value="BINGOS/Log-Message-0.08"
>0.08
  (BINGOS on 2013-04-25)</option>
<option
  
  value="KANE/Log-Message-0.02"
>0.02
  (KANE on 2008-12-13)</option>
<option
  
  value="KANE/Log-Message-0.01"
>0.01
  (KANE on 2003-05-10)</option>
<optgroup label="BackPAN">'
<option
  
  value="BINGOS/Log-Message-0.06"
>0.06
  (BINGOS on 2013-01-23)</option>
<option
  
  value="BINGOS/Log-Message-0.04"
>0.04
  (BINGOS on 2011-01-07)</option>
</optgroup>
</select>
    </li>

    <li>
<ul class="dependencies">
  <li class="nav-header">Dependencies</li>
  <li><a href="https://metacpan.org/pod/File::Spec" title="File::Spec" class="ellipsis">File::Spec</a></li>
  <li><a href="https://metacpan.org/pod/Locale::Maketext::Simple" title="Locale::Maketext::Simple" class="ellipsis">Locale::Maketext::Simple</a></li>
  <li><a href="https://metacpan.org/pod/Module::Load" title="Module::Load" class="ellipsis">Module::Load</a></li>
  <li><a href="https://metacpan.org/pod/Params::Check" title="Params::Check" class="ellipsis">Params::Check</a></li>
  <li><a href="https://metacpan.org/pod/Test::More" title="Test::More" class="ellipsis">Test::More</a></li>
  <li><a href="https://metacpan.org/pod/if" title="if" class="ellipsis">if</a></li>
  <li><i class="ttip" title="dynamic_config enabled">and possibly others</i></li>
  <li>
    <hr>
  </li>
  <li>
    <a href="https://metacpan.org/module/Log::Message/requires">Reverse dependencies</a>
  </li>
  <li>
    <a href="http://deps.cpantesters.org/?module=Log%3A%3AMessage">CPAN Testers List</a>
  </li>
  <li>
    <a href="https://cpandeps.grinnz.com/?dist=Log-Message">Dependency graph</a>
  </li>
</ul>
    </li>
    <li class="nav-header">Permalinks</li>
    <li>
      <a href="https://metacpan.org/release/BINGOS/Log-Message-0.08/view/lib/Log/Message.pm">This version</a>
    </li>
    <li>
      <a href="./Log::Message.html">Latest version</a>
    </li>
    <li>
    </li>
    <li>
<div id="metacpan_contributors">
  <div>
    <button class="btn-link"
      onclick="$(this).hide(); $('#metacpan_contributors ul').slideDown(); return false;"
    >and 1 contributors</button>
  </div>
  <ul style="display: none">
    <li class="contributor"
    >
      Jos Boumans &lt;kane[at]cpan.org&gt;
    </li>
  </ul>
</div>
    </li>
              </ul>
            </div>
          </nav>
          <div class="content-navigation">
<div class="breadcrumbs">
  <span>
    <a data-keyboard-shortcut="g a" rel="author" href="https://metacpan.org/author/BINGOS" class="author-name">Chris Williams</a>
  </span>
  <span>&nbsp;/&nbsp;</span>
  <div class="release dist-release status-latest maturity-released">
    <span class="dropdown"><b class="caret"></b></span>
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/lib/Log/Message.pm&#39;" class="">
<option
  selected
  value="BINGOS/Log-Message-0.08"
>0.08
  (BINGOS on 2013-04-25)</option>
<option
  
  value="KANE/Log-Message-0.02"
>0.02
  (KANE on 2008-12-13)</option>
<option
  
  value="KANE/Log-Message-0.01"
>0.01
  (KANE on 2003-05-10)</option>
<optgroup label="BackPAN">'
<option
  
  value="BINGOS/Log-Message-0.06"
>0.06
  (BINGOS on 2013-01-23)</option>
<option
  
  value="BINGOS/Log-Message-0.04"
>0.04
  (BINGOS on 2011-01-07)</option>
</optgroup>
</select>
    <a data-keyboard-shortcut="g d" class="release-name" href="https://metacpan.org/dist/Log-Message">Log-Message-0.08</a>
  </div>
<span class="river-gauge-gauge">
  <svg width="24px"
       height="15px"
       version="1.1"
       xmlns="http://www.w3.org/2000/svg"
       xmlns:xlink="http://www.w3.org/1999/xlink">

    <g>
      <title>        River stage three &#10;
          • 4 direct dependents &#10;          • 732 total dependents
      </title>

      <rect x="0"  y="0" width="4" height="15" fill="#7ea3f2" />
      <rect x="5"  y="0" width="4" height="15" fill="#7ea3f2" />
      <rect x="10"  y="0" width="4" height="15" fill="#7ea3f2" />
      <rect x="15"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="20"  y="0" width="4" height="15" fill="#e4e2e2" />
    </g>
  </svg>

</span>
<div id="Log-Message-fav" class="logged_in">
<form action="https://metacpan.org/account/favorite/add" style="display: inline" onsubmit="return favDistribution(this)">
    <input type="hidden" name="remove" value="0">
    <input type="hidden" name="release" value="Log-Message-0.08">
    <input type="hidden" name="author" value="BINGOS">
    <input type="hidden" name="distribution" value="Log-Message">
    <button type="submit" class="favorite"><span></span> ++</button>
</form>
</div>
<div class="logged_out">
<a href="./Log::Message.html" onclick="alert('Please sign in to add favorites'); return false" class="favorite">
<span></span> ++</a>
</div>
   / <span>Log::Message</span>
</div>
          </div>
          <main class="content">


<nav class="toc">
  <div class="toc-header"><strong>Contents</strong></div>
<ul>
  <li><a href="./Log::Message.html#NAME">NAME</a></li>
  <li><a href="./Log::Message.html#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="./Log::Message.html#DESCRIPTION">DESCRIPTION</a></li>
  <li><a href="./Log::Message.html#Hierarchy">Hierarchy</a></li>
  <li><a href="./Log::Message.html#Options">Options</a></li>
  <li><a href="./Log::Message.html#Methods">Methods</a>
    <ul>
      <li><a href="./Log::Message.html#new">new</a></li>
      <li><a href="./Log::Message.html#store">store</a></li>
      <li><a href="./Log::Message.html#retrieve">retrieve</a></li>
      <li><a href="./Log::Message.html#first">first</a></li>
      <li><a href="./Log::Message.html#last">last</a></li>
      <li><a href="./Log::Message.html#flush">flush</a></li>
    </ul>
  </li>
  <li><a href="./Log::Message.html#SEE-ALSO">SEE ALSO</a></li>
  <li><a href="./Log::Message.html#AUTHOR">AUTHOR</a></li>
  <li><a href="./Log::Message.html#Acknowledgements">Acknowledgements</a></li>
  <li><a href="./Log::Message.html#COPYRIGHT">COPYRIGHT</a></li>
</ul></nav>
<div class="pod anchors">
<h1 id="NAME">NAME</h1>

<p>Log::Message - A generic message storing mechanism;</p>

<h1 id="SYNOPSIS">SYNOPSIS</h1>

<pre><code>    use Log::Message private =&gt; 0, config =&gt; &#39;/our/cf_file&#39;;

    my $log = Log::Message-&gt;new(    private =&gt; 1,
                                    level   =&gt; &#39;log&#39;,
                                    config  =&gt; &#39;/my/cf_file&#39;,
                               );

    $log-&gt;store(&#39;this is my first message&#39;);

    $log-&gt;store(    message =&gt; &#39;message #2&#39;,
                    tag     =&gt; &#39;MY_TAG&#39;,
                    level   =&gt; &#39;carp&#39;,
                    extra   =&gt; [&#39;this is an argument to the handler&#39;],
               );

    my @last_five_items = $log-&gt;retrieve(5);

    my @items = $log-&gt;retrieve( tag     =&gt; qr/my_tag/i,
                                message =&gt; qr/\d/,
                                remove  =&gt; 1,
                              );

    my @items = $log-&gt;final( level =&gt; qr/carp/, amount =&gt; 2 );

    my $first_error = $log-&gt;first()

    # croak with the last error on the stack
    $log-&gt;final-&gt;croak;

    # empty the stack
    $log-&gt;flush();</code></pre>

<h1 id="DESCRIPTION">DESCRIPTION</h1>

<p>Log::Message is a generic message storage mechanism. It allows you to store messages on a stack -- either shared or private -- and assign meta-data to it. Some meta-data will automatically be added for you, like a timestamp and a stack trace, but some can be filled in by the user, like a tag by which to identify it or group it, and a level at which to handle the message (for example, log it, or die with it)</p>

<p>Log::Message also provides a powerful way of searching through items by regexes on messages, tags and level.</p>

<h1 id="Hierarchy">Hierarchy</h1>

<p>There are 4 modules of interest when dealing with the Log::Message::* modules:</p>

<dl>

<dt id="Log::Message"><a id="Log"></a>Log::Message</dt>
<dd>

<p>Log::Message provides a few methods to manipulate the stack it keeps. It has the option of keeping either a private or a public stack. More on this below.</p>

</dd>
<dt id="Log::Message::Item"><a id="Log1"></a>Log::Message::Item</dt>
<dd>

<p>These are individual message items, which are objects that contain the user message as well as the meta-data described above. See the <a href="./Log::Message::Item.html">Log::Message::Item</a> manpage to see how to extract this meta-data and how to work with the Item objects. You should never need to create your own Item objects, but knowing about their methods and accessors is important if you want to write your own handlers. (See below)</p>

</dd>
<dt id="Log::Message::Handlers"><a id="Log2"></a>Log::Message::Handlers</dt>
<dd>

<p>These are a collection of handlers that will be called for a level that is used on a <a href="./Log::Message::Item.html">Log::Message::Item</a> object. For example, if a message is logged with the &#39;carp&#39; level, the &#39;carp&#39; handler from <a href="./Log::Message::Handlers.html">Log::Message::Handlers</a> will be called. See the <a href="./Log::Message::Handlers.html">Log::Message::Handlers</a> manpage for more explanation about how handlers work, which one are available and how to create your own.</p>

</dd>
<dt id="Log::Message::Config"><a id="Log3"></a>Log::Message::Config</dt>
<dd>

<p>Per Log::Message object, there is a configuration required that will fill in defaults if the user did not specify arguments to override them (like for example what tag will be set if none was provided), <a href="./Log::Message::Config.html">Log::Message::Config</a> handles the creation of these configurations.</p>

<p>Configuration can be specified in 4 ways:</p>

<ul>

<li><p>As a configuration file when you <code>use Log::Message</code></p>

</li>
<li><p>As arguments when you <code>use Log::Message</code></p>

</li>
<li><p>As a configuration file when you create a new <a href="./Log::Message.html">Log::Message</a> object. (The config will then only apply to that object if you marked it as private)</p>

</li>
<li><p>As arguments when you create a new Log::Message object.</p>

<p>You should never need to use the <a href="./Log::Message::Config.html">Log::Message::Config</a> module yourself, as this is transparently done by <a href="./Log::Message.html">Log::Message</a>, but its manpage does provide an explanation of how you can create a config file.</p>

</li>
</ul>

</dd>
</dl>

<h1 id="Options">Options</h1>

<p>When using Log::Message, or creating a new Log::Message object, you can supply various options to alter its behaviour. Of course, there are sensible defaults should you choose to omit these options.</p>

<p>Below an explanation of all the options and how they work.</p>

<dl>

<dt id="config">config</dt>
<dd>

<p>The path to a configuration file to be read. See the manpage of <a href="./Log::Message::Config.html">Log::Message::Config</a> for the required format</p>

<p>These options will be overridden by any explicit arguments passed.</p>

</dd>
<dt id="private">private</dt>
<dd>

<p>Whether to create, by default, private or shared objects. If you choose to create shared objects, all Log::Message objects will use the same stack.</p>

<p>This means that even though every module may make its own $log object they will still be sharing the same error stack on which they are putting errors and from which they are retrieving.</p>

<p>This can be useful in big projects.</p>

<p>If you choose to create a private object, then the stack will of course be private to this object, but it will still fall back to the shared config should no private config or overriding arguments be provided.</p>

</dd>
<dt id="verbose">verbose</dt>
<dd>

<p>Log::Message makes use of another module to validate its arguments, which is called <a href="https://metacpan.org/pod/Params::Check">Params::Check</a>, which is a lightweight, yet powerful input checker and parser. (See the <a href="https://metacpan.org/pod/Params::Check">Params::Check</a> manpage for details).</p>

<p>The verbose setting will control whether this module will generate warnings if something improper is passed as input, or merely silently returns undef, at which point Log::Message will generate a warning.</p>

<p>It&#39;s best to just leave this at its default value, which is &#39;1&#39;</p>

</dd>
<dt id="tag">tag</dt>
<dd>

<p>The tag to add to messages if none was provided. If neither your config, nor any specific arguments supply a tag, then Log::Message will set it to &#39;NONE&#39;</p>

<p>Tags are useful for searching on or grouping by. For example, you could tag all the messages you want to go to the user as &#39;USER ERROR&#39; and all those that are only debug information with &#39;DEBUG&#39;.</p>

<p>At the end of your program, you could then print all the ones tagged &#39;USER ERROR&#39; to STDOUT, and those marked &#39;DEBUG&#39; to a log file.</p>

</dd>
<dt id="level">level</dt>
<dd>

<p><code>level</code> describes what action to take when a message is logged. Just like <code>tag</code>, Log::Message will provide a default (which is &#39;log&#39;) if neither your config file, nor any explicit arguments are given to override it.</p>

<p>See the Log::Message::Handlers manpage to see what handlers are available by default and what they do, as well as to how to add your own handlers.</p>

</dd>
<dt id="remove">remove</dt>
<dd>

<p>This indicates whether or not to automatically remove the messages from the stack when you&#39;ve retrieved them. The default setting provided by Log::Message is &#39;0&#39;: do not remove.</p>

</dd>
<dt id="chrono">chrono</dt>
<dd>

<p>This indicates whether messages should always be fetched in chronological order or not. This simply means that you can choose whether, when retrieving items, the item most recently added should be returned first, or the one that had been added most long ago.</p>

<p>The default is to return the newest ones first</p>

</dd>
</dl>

<h1 id="Methods">Methods</h1>

<h2 id="new">new</h2>

<p>This creates a new Log::Message object; The parameters it takes are described in the <code>Options</code> section below and let it just be repeated that you can use these options like this:</p>

<pre><code>    my $log = Log::Message-&gt;new( %options );</code></pre>

<p>as well as during <code>use</code> time, like this:</p>

<pre><code>    use Log::Message option1 =&gt; value, option2 =&gt; value</code></pre>

<p>There are but 3 rules to keep in mind:</p>

<ul>

<li><p>Provided arguments take precedence over a configuration file.</p>

</li>
<li><p>Arguments to new take precedence over options provided at <code>use</code> time</p>

</li>
<li><p>An object marked private will always have an empty stack to begin with</p>

</li>
</ul>

<h2 id="store">store</h2>

<p>This will create a new Item object and store it on the stack.</p>

<p>Possible arguments you can give to it are:</p>

<dl>

<dt id="message">message</dt>
<dd>

<p>This is the only argument that is required. If no other arguments are given, you may even leave off the <code>message</code> key. The argument will then automatically be assumed to be the message.</p>

</dd>
<dt id="tag1">tag</dt>
<dd>

<p>The tag to add to this message. If not provided, Log::Message will look in your configuration for one.</p>

</dd>
<dt id="level1">level</dt>
<dd>

<p>The level at which this message should be handled. If not provided, Log::Message will look in your configuration for one.</p>

</dd>
<dt id="extra">extra</dt>
<dd>

<p>This is an array ref with arguments passed to the handler for this message, when it is called from store();</p>

<p>The handler will receive them as a normal list</p>

</dd>
</dl>

<p>store() will return true upon success and undef upon failure, as well as issue a warning as to why it failed.</p>

<h2 id="retrieve">retrieve</h2>

<p>This will retrieve all message items matching the criteria specified from the stack.</p>

<p>Here are the criteria you can discriminate on:</p>

<dl>

<dt id="tag2">tag</dt>
<dd>

<p>A regex to which the tag must adhere. For example <code>qr/\w/</code>.</p>

</dd>
<dt id="level2">level</dt>
<dd>

<p>A regex to which the level must adhere.</p>

</dd>
<dt id="message1">message</dt>
<dd>

<p>A regex to which the message must adhere.</p>

</dd>
<dt id="amount">amount</dt>
<dd>

<p>Maximum amount of errors to return</p>

</dd>
<dt id="chrono1">chrono</dt>
<dd>

<p>Return in chronological order, or not?</p>

</dd>
<dt id="remove1">remove</dt>
<dd>

<p>Remove items from the stack upon retrieval?</p>

</dd>
</dl>

<p>In scalar context it will return the first item matching your criteria and in list context, it will return all of them.</p>

<p>If an error occurs while retrieving, a warning will be issued and undef will be returned.</p>

<h2 id="first">first</h2>

<p>This is a shortcut for retrieving the first item(s) stored on the stack. It will default to only retrieving one if called with no arguments, and will always return results in chronological order.</p>

<p>If you only supply one argument, it is assumed to be the amount you wish returned.</p>

<p>Furthermore, it can take the same arguments as <code>retrieve</code> can.</p>

<h2 id="last">last</h2>

<p>This is a shortcut for retrieving the last item(s) stored on the stack. It will default to only retrieving one if called with no arguments, and will always return results in reverse chronological order.</p>

<p>If you only supply one argument, it is assumed to be the amount you wish returned.</p>

<p>Furthermore, it can take the same arguments as <code>retrieve</code> can.</p>

<h2 id="flush">flush</h2>

<p>This removes all items from the stack and returns them to the caller</p>

<h1 id="SEE-ALSO"><a id="SEE"></a>SEE ALSO</h1>

<p><a href="./Log::Message::Item.html">Log::Message::Item</a>, <a href="./Log::Message::Handlers.html">Log::Message::Handlers</a>, <a href="./Log::Message::Config.html">Log::Message::Config</a></p>

<h1 id="AUTHOR">AUTHOR</h1>

<p>This module by Jos Boumans &lt;kane@cpan.org&gt;.</p>

<h1 id="Acknowledgements">Acknowledgements</h1>

<p>Thanks to Ann Barcomb for her suggestions.</p>

<h1 id="COPYRIGHT">COPYRIGHT</h1>

<p>This module is copyright (c) 2002 Jos Boumans &lt;kane@cpan.org&gt;. All rights reserved.</p>

<p>This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.</p></div>

<div id="metacpan_install-instructions-dialog" class="modal fade">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
        <h4 class="modal-title">Module Install Instructions</h4>
      </div>
      <div class="modal-body">
        <p>To install Log::Message, copy and paste the appropriate command in to your terminal.</p>
        <p><a href="https://metacpan.org/dist/App-cpanminus/view/bin/cpanm">cpanm</a></p>
        <pre><code>cpanm Log::Message</code></pre>
        <p><a href="https://metacpan.org/pod/CPAN">CPAN shell</a></p>
        <pre><code>perl -MCPAN -e shell
install Log::Message</code></pre>
        <p>For more information on module installation, please visit <a href="https://www.cpan.org/modules/INSTALL.html">the detailed CPAN module installation guide</a>.</p>
      </div>
      <div class="modal-footer">
        <a href="./Log::Message.html#" data-dismiss="modal" class="btn">Close</a>
      </div>
    </div>
  </div>
</div>
          </main>
          <div class="content-pagination">
          </div>
        </div>
        <footer class="footer">
          <div class="footer-container">
            <div class="footer-social">
              <div class="footer-link footer-logo">
                <a href="https://metacpan.org/">
                  <img src="https://metacpan.org/static/images/metacpan-logo.svg" alt="MetaCPAN" />
                </a>
              </div>
              <a class="footer-social-link" href="https://github.com/metacpan">
                <i class="fab fa-github-square"></i>
              </a>
              <a class="footer-social-link" href="https://fosstodon.org/@metacpan">
                <i class="fab fa-mastodon"></i>
              </a>
            </div>
            <div class="footer-links">
              <div class="footer-link">
                  <a href="https://metacpan.org/about">About</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/sponsors">Sponsor</a>
              </div>
              <div class="footer-link">
                  <a href="https://grep.metacpan.org">grep::cpan</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/recent">Recent</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/faq">FAQ</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/tools">Tools</a>
              </div>
              <div class="footer-link">
                  <a href="https://fastapi.metacpan.org/">API</a>
              </div>
              <div class="footer-link">
                  <a href="https://www.perl.org/">Perl.org</a>
              </div>
            </div>
            <div class="footer-sponsors">
              <a class="footer-sponsor-link" target="_blank" href="https://www.bytemark.co.uk/" rel="noopener">
                <img class="footer-sponsor-bytemark" src="https://metacpan.org/static/images/sponsors/bytemark_logo.svg" alt="Bytemark logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.liquidweb.com/" rel="noopener">
                <img class="footer-sponsor-liquidweb" src="https://metacpan.org/static/images/sponsors/liquidweb_logo.png" alt="liquidweb logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://deriv.com/careers/" rel="noopener">
                <img class="footer-sponsor-deriv" src="https://metacpan.org/static/images/sponsors/deriv.svg" alt="Deriv logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://geocode.xyz" rel="noopener">
                <img class="footer-sponsor-geocode" src="https://metacpan.org/static/images/sponsors/geocodelogo.svg" alt="Geocode logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.fastly.com/" rel="noopener">
                <img class="footer-sponsor-fastly" src="https://metacpan.org/static/images/sponsors/fastly_logo.svg" alt="Fastly logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://opencagedata.com" rel="noopener">
                <img class="footer-sponsor-opencage" src="https://metacpan.org/static/images/sponsors/open-cage.svg" alt="OpenCage logo">
              </a>
            </div>
          </div>
        </footer>
        <div class="modal fade" tabindex="-1" role="dialog" id="metacpan_keyboard-shortcuts">
          <div class="modal-dialog">
            <div class="modal-content">
              <div class="modal-header">
                <button type="button" class="close" data-dismiss="modal">&times;</button>
                <h4 class="modal-title">Keyboard Shortcuts</h4>
              </div>
              <div class="modal-body row">
<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Global</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>s</kbd>
        </td>
        <td>Focus search bar</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>?</kbd>
        </td>
        <td>Bring up this help dialog</td>
      </tr>
    </tbody>
  </table>

  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>GitHub</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>p</kbd>
        </td>
        <td>Go to pull requests</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>go to github issues (only if github is preferred repository)</td>
      </tr>
    </tbody>
  </table>
</div>

<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>POD</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>a</kbd>
        </td>
        <td>Go to author</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>c</kbd>
        </td>
        <td>Go to changes</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>Go to issues</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>d</kbd>
        </td>
        <td>Go to dist</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>r</kbd>
        </td>
        <td>Go to repository/SCM</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>s</kbd>
        </td>
        <td>Go to source</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>b</kbd>
        </td>
        <td>Go to file browse</td>
      </tr>

    </tbody>
  </table>
</div>

<div class="col-md-12">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Search terms</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><em>module:</em> (e.g. <a href="https://metacpan.org/search?q=module%3APlugin">module:Plugin</a>)</td>
      </tr>
      <tr>
        <td><em>distribution:</em> (e.g. <a href="https://metacpan.org/search?q=distribution%3ADancer+auth">distribution:Dancer auth</a>)</td>
      </tr>
      <tr>
        <td><em>author:</em> (e.g. <a href="https://metacpan.org/search?q=author%3ASONGMU+Redis">author:SONGMU Redis</a>)</td>
      </tr>
      <tr>
        <td><em>version:</em> (e.g. <a href="https://metacpan.org/search?q=version%3A1.00">version:1.00</a>)</td>
      </tr>
    </tbody>
  </table>
</div>
              </div>
              <div class="modal-footer"></div>
            </div>
          </div>
        </div>
    </body>
</html>
